Repository navigation
fix: affinity selection scored a protein the cell does not express - #51
Merged
Merged
Conversation
`blosum62` falls through to -4 for any character outside the twenty residues, and `substitution_cost` is `S(a,a) - S(a,b)`. For a stop or an unresolved `X` in the cell both terms were that same -4, so the cost cancelled to exactly zero against every target residue, distance was 0, and `affinity = exp(-beta * 0) = 1.0` -- the maximum. A cell whose receptor cannot be translated scored as a perfect match to any antigen. The asymmetry is what gives it away: a stop in the *target* cost the full amount, a stop in the cell was free. Reproduced on the real model: a `KPGT*` cell reported affinity 1.0 against `KPGTA`, `KPGTW` and `KPGTAAAAAAAA` alike. A character that is not a residue is now charged `MAX_SUBSTITUTION_COST`, so it cannot be cheaper than a substitution between two real residues. The constant is 15 -- `S(W,W) - S(W,D)` -- and `max_real_substitution_cost_is_the_constant` derives that maximum from the matrix rather than trusting the number. Two comments were also wrong. `blosum62` claimed non-standard residues "contribute maximally to distance", which the cancellation made false, and `substitution_cost` claimed its result "grows as the substitution becomes less favorable", which held for every pair except the ones that matter most. The maximal-contribution rule now lives where it can see which side the non-residue is on, and `idx` is lifted out of `blosum62` as `residue_index` so both can use it. This is the smaller half of the defect. The translation that decides which residues are scored at all is still wrong; that is the next commit, and it is what moves the determinism version.
`sim_to_aa` concatenated the per-region codon rail, and `compute_codon_rail` keeps a codon only if it fits wholly inside one region. Every region boundary in a rearrangement is a junction boundary, so the residues selection could not see were exactly the ones it exists to select on. Measured over 200 human_igh records: 2.68 codons dropped per record, range 0 to 4, and 536 of 536 of them straddling V/NP1, NP1/D, D/NP2 or NP2/J. The frame did not restart -- each region's phase is its pool offset -- so every scored codon was real; the dropped ones simply vanished and shifted the indices after them left. For one record the scored protein began VYYCARGYCSSTSC where the real one is VYYCARDRGYCSSTSC*KK: the loss starts at the conserved CDR3 anchor and carries through CDR3 and J. The end-to-end consequence, through the public API: a cell grown with rate=0, so identical to its founder, scored against the founder's own protein reported an affinity of 3.57e-67 instead of 1. The model could not recognise a cell as identical to itself. Both paths now use the continuous coding-span translation that the duplex and family-replay paths already used, renamed from `duplex_sim_to_aa` to `coding_sim_to_aa` because it was never duplex-specific. It agrees with the record's own `sequence_aa`, which the projection derives independently from `coding_frame_start`, and that independence is what makes the new tests evidence rather than a tautology. The reference is not optional for this: `coding_span` resolves the frame from the V allele's native phase, its 5' trim and its observation loss, so translating from pool position zero can be in the wrong frame entirely. An affinity model therefore travels with its `RefDataConfig` as a pair rather than borrowing one from the mutation context -- passing a context exists to select the mutator's execution policy, and giving the neutral path one just to reach its reference would move its draws. `simulate_lineage` now requires refdata when selection is active. Under active selection a cell whose coding span contains a stop expresses no receptor, receives no survival signal, and leaves no offspring. Scoped to active selection deliberately: at selection_strength 0 fitness is identically 1 for every cell, which is documented and tested, and lethality is part of a selection model rather than something to assert over a run the caller asked to be neutral. A supplied target_aa must now be exactly as long as the receptor it is scored against. `weighted_aa_distance` compares min(len, len) positions and ignores the rest, so a truncated or over-long target scored silently -- KPGTA and KPGTAAAAAAAA were equidistant from a cell. Validated at the PyO3 boundary, where callers are; internal constructions still build whatever they need for range tests. The three affinity growth tests scored the broken rail on a four-base synthetic founder with no V assignment. They now use a founder with a resolved assignment and its reference. That fixture's boundaries are all codon-aligned, which is why they passed before: it is the case that drops nothing. DETERMINISM_VERSION 3 -> 4. Seed-moving wherever selection is active.
Lethality was the intended rule and it had to be withdrawn. Measured on human_igh, the share of sampled cells whose coding span contains a stop: 96% at the default rate=0.05 (110/115), 89% at 0.01, and 50% even at rate=0, inherited from founders -- 108 of 200 of which carry one already, because recombine() does not constrain productivity and clonal_lineage does not require it. Giving those cells no offspring extinguishes essentially every family, and clonal_lineage(selection_strength>0) then fails outright after exhausting its 50 survival retries. That is not a germinal center; it is a mutation model that produces mostly untranslatable receptors, which is a separate problem from how affinity scores them. A stop still carries the maximal substitution cost, so a receptor that cannot be translated is scored far from the target rather than as a perfect match, which was the reproduced defect. Making lethality viable means constraining SHM to keep the receptor productive first -- rejecting stop-causing proposals is a different process from letting lethal mutations reduce survival, and it has to come before this scoring change, not with it. An earlier draft of the rule also applied at selection_strength 0, which silently overrode the documented guarantee that fitness is identically 1 there. It passed affinity_strength_zero_matches_neutral_topology only because that fixture's founder carries no stop. The guide and changelog carry the 96% figure, so a reader does not take lineage_affinity on a stop-bearing cell for a statement that the cell is viable. They also record that a supplied target must match the receptor's protein length, that the length is discoverable only from the refusal (sampled cells are mutated descendants and differ in length), and that this makes an explicit target single-clone in practice, since each clone has its own founder. Two affinity tests encoded the defect's assumptions and are updated here. test_affinity_selection_raises_mean_affinity used target_aa="A" * 100 with the note "target length need not match; distance uses min length" -- the defect stated as a design choice. It now builds a target from the founder's own protein, taken from the record projection rather than the affinity path, so the length is right by construction. test_clonal_lineage_selection_raises_mean_affinity is replaced rather than repaired, and the inventory declaration carries the argument. Its 100-residue target made every affinity underflow to near zero, which is what made its comparison stable. With real distances the claim is not stably testable at DSL level: over 7 to 17 sampled cells the mean is sampling noise -- 0.637, 0.642, 0.634, 0.631, 0.628, 0.651 across strengths 0.05 to 0.7 -- and a strength large enough to separate the arms drives fitness to zero for diverged cells and extinguishes the family. The claim stays at engine level where the founder can be pinned and the target sized. The successor keeps what only the DSL can break: the keyword reaching the engine, affinities populated and in range, and a neutral run reporting 0.0 because it builds no model at all. The six reproducibility goldens change by one field again, determinism_version 3 to 4. No golden grows a lineage or scores an affinity, so nothing here measures the new model.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Affinity selection translated each region of a cell separately and
concatenated the results.
compute_codon_railkeeps a codon only if it fitswholly inside one region, so every codon straddling a region boundary was
dropped — and every region boundary in a rearrangement is a junction boundary.
What it cost
A cell grown with
rate=0, and therefore identical to its founder, scoredagainst the founder's own protein reported an affinity of
3.57e-67instead of1.0. The model could not recognise a cell as identical to itself.Measured over 200
human_ighrecords:The frame did not restart — each region's phase is its pool offset, so every
scored codon was real. The dropped ones simply vanished and shifted every
amino-acid position after them left. For one record the scored protein began
VYYCARGYCSSTSCwhere the real one isVYYCARDRGYCSSTSC*KK: the loss startsat the conserved CDR3 anchor and carries through CDR3 and J. Records whose
boundaries happen to be codon-aligned lose nothing, which is why the count is
not simply one per boundary.
A stop codon scored as the perfect antibody
Separately,
substitution_costisS(a,a) - S(a,b), and for a stop or anunresolved
Xboth terms fell through to the same-4. The cost cancelled toexactly zero against every target residue, so distance was 0 and
affinity = exp(-beta · 0) = 1.0, the maximum. AKPGT*cell reported affinity1.0 against
KPGTA,KPGTWandKPGTAAAAAAAAalike. The asymmetry is thetell: a stop in the target cost the full amount, a stop in the cell was free.
Two comments were also wrong —
blosum62claimed non-standard residues"contribute maximally to distance", which the cancellation made false, and
substitution_costclaimed its result grows as the substitution becomes lessfavourable, true for every pair except the ones that matter most.
The fix
Both paths now use the continuous coding-span translation the duplex and
family-replay paths already used, renamed
duplex_sim_to_aa→coding_sim_to_aabecause it was never duplex-specific. It agrees with therecord's own
sequence_aa, which the projection derives independently fromcoding_frame_start— and that independence is what makes the new testsevidence rather than a tautology.
The reference is not optional:
coding_spanresolves the frame from the Vallele's native phase, its 5' trim and its observation loss, so translating from
pool position zero can be in the wrong frame entirely. An affinity model
therefore travels paired with its
RefDataConfigrather than borrowing onefrom the mutation context — passing a context also selects the mutator's
execution policy, so giving the neutral path one just to reach its reference
would move its draws.
simulate_lineagenow requiresrefdatawhen selectionis active.
A non-residue is charged the maximal substitution cost (15,
S(W,W) - S(W,D),derived from the matrix by its own test rather than trusted).
A supplied
target_aamust now be exactly as long as the receptor it scores.The distance compared
min(len, len)positions and ignored the rest, so atruncated or over-long target scored silently and reported a number that was not
a distance to it.
A stop is penalised, not lethal — and why
Lethality was the intended rule and had to be withdrawn after measuring what it
costs. Share of sampled
human_ighcells whose coding span contains a stop:and 108 of 200 default founders (54%) carry one already, because
recombine()does not constrain productivity and
clonal_lineagedoes not require it.Giving those cells no offspring extinguishes essentially every family and makes
clonal_lineage(selection_strength>0)fail outright after its 50 survivalretries. That the mutation model produces mostly untranslatable receptors is a
separate problem from how affinity scores them; making lethality viable means
constraining SHM to keep the receptor productive first. The 96% figure is in the
guide and changelog so
lineage_affinityon a stop-bearing cell is not read asa statement that the cell is viable.
Tests
tests/components/clonal/test_lineage_affinity_translation.pypins thetranslation against the independent
sequence_aaoracle, verified to equal acontinuous translation of the coding span before being relied on.
Two existing tests encoded the defect's assumptions.
test_affinity_selection_raises_mean_affinityusedtarget_aa="A" * 100withthe note "target length need not match; distance uses min length" — the defect
stated as a design choice.
test_clonal_lineage_selection_raises_mean_affinityis replaced rather than repaired: its 100-residue target made every affinity
underflow to near zero, which is what made its comparison stable, and with real
distances the claim is not stably testable at DSL level (over 7–17 sampled cells
the mean is sampling noise — 0.637, 0.642, 0.634, 0.631, 0.628, 0.651 across
strengths 0.05–0.7). The claim stays at engine level where the founder can be
pinned and the target sized; the successor keeps what only the DSL can break.
The inventory declaration carries the full argument.
The three affinity growth tests scored the broken rail on a four-base synthetic
founder with no V assignment. They now use a founder with a resolved assignment
and its reference. That fixture's pool is
AAA TGT ACT TTT AAA— every boundarycodon-aligned — which is exactly why they passed before.
Compatibility
DETERMINISM_VERSION3 → 4. Seed-moving wherever selection is active;selection_strength=0runs with no target are unaffected. The sixreproducibility goldens differ in one field,
determinism_version— no goldengrows a lineage or scores an affinity, so nothing there measures the new model.
Affinity numbers from before version 4 are not comparable with these, and
neither are the genealogies selection shaped. Neither "all published results
invalid" nor "few runs affected" is established — that needs an audit of
released runs with
selection_strength > 0.Not claimed
This validates the input to the selection model. BLOSUM62 distance to an
artificial receptor-sequence target remains a synthetic fitness landscape, not
antigen binding, and the per-position weights are still uniform despite a
comment promising CDR3 weighting.
Gates
pytest 5865 passed / 17 skipped; performance 9 passed serial; cargo 1742 passed
across 6 suites; ruff clean; inventory gate clean with
--declarations.